\defmodule{StochasticProcess}

Abstract base class for a stochastic process $\{X(t) : t \geq 0 \}$
sampled (or observed) at a finite number of time points,
$0 = t_0 < t_1 < \cdots < t_d$.
The observation times are usually all specified before generating a sample path.
This can be done via \texttt{setObservationTimes}.
The method \texttt{generatePath} generates $X(t_1),\dots,X(t_d)$ and memorizes
them in a vector, which can be recovered by \texttt{getPath}.

Alternatively, for some types of processes, the observations $X(t_j)$ can be
generated sequentially, one at a time, by invoking  \texttt{resetStartProcess}
first, and then \texttt{nextObservation} repeatedly.
For some types of processes, the observation times can be specified one by one
as well, when generating the path.  This may be convenient or even necessary
if the observation times are random, for example.

\textbf{WARNING: After having called the constructor for one of the subclass,
 one must always set the observation times of the process,
 by calling method \texttt{setObservationTimes} for example or otherwise.}



\bigskip\hrule\bigskip

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{code}
\begin{hide}
/*
 * Class:        StochasticProcess
 * Description:  Base class for all stochastic processes
 * Environment:  Java
 * Software:     SSJ 
 * Copyright (C) 2001  Pierre L'Ecuyer and Universite de Montreal
 * Organization: DIRO, Universite de Montreal
 * @author       
 * @since

 * SSJ is free software: you can redistribute it and/or modify it under
 * the terms of the GNU General Public License (GPL) as published by the
 * Free Software Foundation, either version 3 of the License, or
 * any later version.

 * SSJ is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.

 * A copy of the GNU General Public License is available at
   <a href="http://www.gnu.org/licenses">GPL licence site</a>.
 */
\end{hide}
package umontreal.iro.lecuyer.stochprocess;\begin{hide}
import umontreal.iro.lecuyer.rng.RandomStream;
\end{hide}


public abstract class StochasticProcess \begin{hide} {
    // Used in some subclasses to make sure the 'setObservationTimes'
    // method has already been invoked before calling 'init'
    protected boolean observationTimesSet = false;

    protected double x0 = 0.0;       // Default Initial Value of the process
    protected int d = -1;             // Num. of observation times
    protected int observationIndex = 0; // Index of last generated obs time
    protected int observationCounter = 0; // Counts how many observations have
              // been generated so far. Useful when they are not generated in
              // chronological order.
    protected double[] t;            // Observation times
    protected double[] path;            // Observations of the process
    //protected RandomStream stream; // Random stream used to generate the process
    protected int[] observationIndexFromCounter; // Links counter# to index#
\end{hide}
\end{code}

\subsubsection* {Methods}
\begin{code}

   public void setObservationTimes (double[] T, int d)\begin{hide} {
        if (d <= 0) throw new IllegalArgumentException (
                    "Number of observation times d <= 0");
        this.d = d;
        observationTimesSet = true;

        // Copy of the observation times
        this.t = new double[d+1];
        System.arraycopy (T, 0, this.t, 0, d+1);

        // Test chronological order
        for (int i = 0; i < d; i++) {
            if (T[i+1] < T[i])
                throw new IllegalArgumentException (
                     "Observation times T[] are not time-ordered");
        }

        // Construction of 'path' object
        // We do not do it in 'init()' because we don't have to change the
        // path object if the user only calls 'setParams'
        path = new double[d+1];

        /* Process specific initialization; usually precomputes quantities
             that depend on the observation times.   */
        init();
    } \end{hide}
\end{code}
\begin{tabb}
Sets the observation times of the process to a copy of \texttt{T},
with $t_{0} =$ \texttt{T[0]} and $t_{d} =$ \texttt{T[d]}.
The size of \texttt{T} must be $d+1$.
\end{tabb}
\begin{code}

   public void setObservationTimes (double delta, int d)\begin{hide} {
        t = new double[d+1];
        for (int i=0; i<=d; i++) t[i] = i*delta;
        setObservationTimes (t, d);
    } \end{hide}
\end{code}
\begin{tabb} Sets equidistant observation times at $t_j = j\delta$, for $j=0,\dots,d$, and \texttt{delta} = $\delta$.
\end{tabb}
\begin{code}

   public double[] getObservationTimes() \begin{hide} {
        return t;
    }\end{hide}
\end{code}
\begin{tabb} Returns a reference to the array that contains the observation times
$(t_0,\dots,t_d)$.
\emph{Warning}: This method should only be used to \emph{read} the observation times.
Changing the values in the array directly may have unexpected consequences.
The method \texttt{setObservationTimes} should be used to modify the observation times.
\end{tabb}
\begin{code}

   public int getNbObservationTimes() \begin{hide} {
        return d;
    }\end{hide}
\end{code}
\begin{tabb} Returns the number of observation times excluding the time $t_{0}$.
\end{tabb}
\begin{code}

   public abstract double[] generatePath();
\end{code}
\begin{tabb} Generates, returns, and saves the sample path
$\{X(t_{0}), X(t_{1}), \ldots, X(t_{d})\}$. It can then be accessed via
\texttt{getPath}, \texttt{getSubpath}, or \texttt{getObservation}.
The generation method depends on the process type.
\end{tabb}
\begin{code}

   public double[] generatePath (RandomStream stream) \begin{hide} {
        setStream (stream);
        return generatePath();
    }\end{hide}
\end{code}
\begin{tabb}
 Same as \texttt{generatePath()}, but first resets the stream to \texttt{stream}.
\end{tabb}
\begin{code}

   public double[] getPath() \begin{hide} {
        return path;
    }\end{hide}
\end{code}
\begin{tabb}
Returns a \emph{reference} to the last generated sample path
$\{X(t_{0}), ... , X(t_{d})\}$.
\emph{Warning}: The returned array and its size should not be modified,
because this is the one that memorizes the observations (not a copy of it).
To obtain a copy, use \texttt{getSubpath} instead.
\end{tabb}
\begin{code}

   public void getSubpath (double[] subpath, int[] pathIndices) \begin{hide} {
        for (int j=0; j<subpath.length; j++) {
            subpath[j] = path[pathIndices[j]];
        }
    }\end{hide}
\end{code}
\begin{tabb}
Returns in \texttt{subpath} the values of the process at a subset of the observation times,
specified as the times $t_{j}$ whose indices $j$ are in the array \texttt{pathIndices}.
The size of \texttt{pathIndices} should be at least as much as that of \texttt{subpath}.
%  in order to avoid an \texttt{ArrayIndexOutOfBoundsException}.
\end{tabb}
\begin{code}

   public double getObservation (int j) \begin{hide} {
        return path[j];
    }\end{hide}
\end{code}
\begin{tabb} Returns $X(t_{j})$ from the current sample path.
\emph{Warning}: If the observation $X(t_{j})$ for the current path has not yet been
generated, then %this method may return the observation from a previous sample path.
the value returned is unpredictable.
\end{tabb}
\begin{code}

   public void resetStartProcess() \begin{hide} {
        observationIndex   = 0;
        observationCounter = 0;
    }\end{hide}
\end{code}
\begin{tabb} Resets the observation counter to its initial value $j=0$, so
that the current observation $X(t_{j})$ becomes $X(t_{0})$. This method should
 be invoked before generating observations sequentially one by one
via \method{nextObservation}{}, for a new sample path.
\end{tabb}
\begin{code}

   public boolean hasNextObservation() \begin{hide} {
        if (observationCounter < d) return true;
        else return false;
    }\end{hide}
\end{code}
\begin{tabb}
Returns \texttt{true} if $j<d$, where $j$ is the number of observations of the current
sample path generated since the last call to \method{resetStartProcess}{}.
Otherwise returns \texttt{false}.
\end{tabb}
\begin{code}

   public double nextObservation()\begin{hide} {
        throw new UnsupportedOperationException("Method not defined in this class");
    }\end{hide}
\end{code}
\begin{tabb}
Generates and returns the next observation $X(t_j)$ of the stochastic process.
The processes are usually sampled \emph{sequentially}, i.e.
if the last observation generated was for time $t_{j-1}$, the next observation
returned will be for time $t_{j}$.
In some cases, subclasses extending this abstract class
may use non-sequential sampling algorithms (such as bridge sampling).
The order of generation of the $t_{j}$'s is then specified by the subclass.
All the processes generated using principal components analysis (PCA) do not have
this method.
\end{tabb}
\begin{code}

   public int getCurrentObservationIndex() \begin{hide} {
        return observationIndex;
    }\end{hide}
\end{code}
\begin{tabb} Returns the value of the index $j$ corresponding to
the time $t_{j}$ of the last generated observation.
\end{tabb}
\begin{code}

   public double getCurrentObservation() \begin{hide} {
        return path[observationIndex];
    }\end{hide}
\end{code}
\begin{tabb} Returns the value of the last generated observation $X(t_{j})$.
\end{tabb}
\begin{code}

   public double getX0() \begin{hide} {
        return x0;
    }\end{hide}
\end{code}
\begin{tabb} Returns the initial value $X(t_{0})$ for this process.
\end{tabb}
\begin{code}

   public void setX0 (double s0) \begin{hide} {
        x0 = s0;
        init();
    }\end{hide}
\end{code}
\begin{tabb} Sets the initial value $X(t_{0})$ for this process to \texttt{s0},
and reinitializes.
\end{tabb}
\begin{code}

   public abstract void setStream (RandomStream stream);
\end{code}
\begin{tabb}
Resets the random stream of the underlying generator to \texttt{stream}.
\end{tabb}
\begin{code}

   public abstract RandomStream getStream();
\end{code}
\begin{tabb}
Returns the random stream of the underlying generator.
\end{tabb}
\begin{code}\begin{hide}

    /*** Called by 'setObservationTimes' to initialize arrays and precompute
         constants to speed up execution. See overriding method 'init'
         in subclasses for details ***/
    protected void init() {
        if (observationTimesSet) //   If observation times are not defined, do nothing.
           path[0] = x0;
           // We do this here because the s0 parameter may have changed through
           // a call to the 'setParams' method.
    }\end{hide}

   public int[] getArrayMappingCounterToIndex() \begin{hide} {
        return observationIndexFromCounter;
    }\end{hide}
\end{code}
\begin{tabb} Returns a reference to an array that maps an integer $k$
to $i_{k}$, the index of the observation $S(t_{i_{k}})$ corresponding
to the $k$-th observation to be generated for a sample path of this process.
If this process is sampled sequentially, then this map is trivial
(i.e. $i_{k} = k$). But it can be useful in a more general setting where
the process is not sampled sequentially
(for example, by a Brownian or gamma bridge) and one wants to know which
observations of the current sample path were previously generated
or will be generated next.
\end{tabb}
\begin{code} \begin{hide}
} \end{hide}
\end{code}
